home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 June / MacFormat 25.iso / Shareware City / Developers / appe Windows 1.51.1 / About appe Windows < prev    next >
Encoding:
Text File  |  1995-01-11  |  6.6 KB  |  162 lines  |  [TEXT/R*ch]
  1. appe Windows
  2.  
  3. If you have seen the new Speech Manager, then you know that a background
  4. only application can put a window onto the screen (contrary to popular
  5. belief). The new Text Services Manager in System 7.1 offers documented
  6. hooks for creating, disposing, and handling floating windows. These
  7. windows are layer independent (they are floating above all programs
  8. and windows), and can work without patching traps (well, a quick jGNEFilter,
  9. but no traps).
  10.  
  11. This program demonstrates a shell application that puts a TSM window
  12. onto the screen, and intercepts update, click, and key events. Filling
  13. in the handler functions is the easiest way to put up your own floater.
  14. Wrapper functions restore global context, current resource file, GrafPort, 
  15. and heap zone, to make standard handling routines much easier to write.
  16.  
  17. The program now works as a foreground or background application. The 
  18. software is distributed as a foreground app, but the process to convert
  19. a program to background app is to set the "Background Only" flag in
  20. the 'SIZE' resource (or Project Flags) and to make a system extension,
  21. you should change the file type from 'APPL' to 'appe'. I have added
  22. a drag-n-drop utility to convert between foreground and background apps, 
  23. as well as a file describing the differences.
  24.  
  25. I like the close box on floater windows, because its an easy way to
  26. quit the program without relying on a quit Apple Event. I have added
  27. support for hiding windows with Cmd-Escape, and to respond to screen
  28. savers and programs that take over the screen (hide the menu bar).
  29.  
  30.  
  31. Legal Stuff
  32.  
  33. Its yours if you like it. This shell is free for you to modify and
  34. expand upon. I would like it if you tell me if you use this, but you
  35. are under no obligation. Likewise, this library is provided as is --
  36. I fixed up all the bugs I could find/create, so I could use it myself --
  37. but that doesnt necessarily mean its fit for wiping the toilet seat. :)
  38.  
  39. The enclosed extension "TSM Fix" is intended to fix problems with the
  40. jGNEFilter missing clicks bug. This INIT is also free, to be distributed
  41. with (or without) any software you have written.
  42.  
  43. In addition, the enclosed utility "appe <-> APPL" is useful so that you
  44. only have to distribute a single binary. Again, the program is free 
  45. to be redistributed at your whim.
  46.  
  47.  
  48. Using the library
  49.  
  50. In scanning the source for the program, there are several key areas
  51. that you should recognize. These gotchas are important things to 
  52. remember when modifying or adding to the source.
  53.  
  54. main.c
  55.     
  56.     Facelss background applications seem to require additional
  57.     stack space. I found that 16k of additional stack seems to
  58.     work. BTW, keep the memory footprint down (cuz people dont like
  59.     memory hogs) but not too small or you will have heap space
  60.     problems. I had to fine tune my demo apps to work well in
  61.     limited memory space.
  62.     
  63.     In a background-only application, the only Toolbox initialization
  64.     call that you should make is InitGraf() to setup the QD globals.
  65.     InitWindows() plays with the layer manager in a bad way, and
  66.     should be avoided.
  67.     
  68.     I use Gestalt() to check my environment, and exit gracefully
  69.     with a Notification Mgr dialog.
  70.     
  71. windows.c
  72.  
  73.     The current TSM does not create a Color Window for us, so there
  74.     is a #define in "main.h" that gives you the option to patch
  75.     traps. Although this violates our promise of Patch-Free operation,
  76.     it gives us color -- so lose or leave it at your whim.
  77.     
  78.     Hooks are set up for you to implement the following window
  79.     functions: Update, Click, Keydowns, Zoom, Reveal (on show
  80.     and hide), and Idle time.
  81.  
  82.     Key events can be intercepted or passed through at your 
  83.     discretion. By default, only Cmd-Escape is applicable and
  84.     it is passed through so that other floaters can see it. 
  85.     (This would be a useful feature for all similar apps to 
  86.     implement, please?)
  87.     
  88.     Controls like scroll bars or other window-activation 
  89.     sensitive elements should always be active in floaters,
  90.     since all floaters are considered active regardless of
  91.     position in window list.
  92.     
  93. event filter.c
  94.  
  95.     The jGNEFilter is the best way to intercept the events
  96.     directed at our window. We check mouse and key events
  97.     for relevance, and then convert them to null events
  98.     if directed at our window.
  99.     
  100.     Note: the jGNEFilter may miss occasional mouse-downs.
  101.     Its a bug in the OS, and you need to look at my "TSM Fix"
  102.     for a patch that rememdies the problem. 
  103.     
  104.     Our floaters dont get update events either, so we manually
  105.     check the update region of our window and call the update
  106.     routine. We have to check every event because update events
  107.     aren't necessarily posted when just our window needs
  108.     drawing.
  109.     
  110.     (v1.51) Updated the InScreenSaver() function to check the
  111.     menubar height ONLY in when in the foreground, or to 
  112.     check the cached height in the background.
  113.     
  114. contexts.c
  115.  
  116.     Contexts are the mechanism we use for setting up and cleaning
  117.     up relevant variables and registers. A context struct
  118.     defines some major elements that I need. Be sure that code
  119.     you add is not dependent on other lo-mem globals without the
  120.     right save and restore context wrappers. Also, since a
  121.     context plays with A5 and your app globals, you have to
  122.     be careful about globally stored contexts.
  123.     
  124.     To get information about the front application, you may need
  125.     to restore its context (to get heap info or access private
  126.     globals off A5). Be sure to carefully manage when you are
  127.     using your apps context and someone elses.
  128.     
  129.     In the first version the resource file was saved and restored
  130.     by its (open) refNum, which turns out to be wrong -- the resource
  131.     chain is *not* universal (thanks Peter Lewis). The current 
  132.     solution is to create a duplicate resource file (clone the app's
  133.     resources), and open/close it each event filter.
  134.     
  135.     (v1.51) Set the location of the temporary file to the 
  136.     temporary items folder now. DOH! If unable, then it
  137.     tries the System Folder, then the app's current folder.
  138.     
  139. Other notes
  140.     
  141.     In "main.h" I define a Hot Application, which lets you tie
  142.     your floater to an particular application creator type. If
  143.     you change this value, your floaters will only be visible 
  144.     when that application is the front program. This is a great
  145.     way to give specialized information about a particular 
  146.     program without modifying it.
  147.     
  148.     Perhaps it would be better to handle events within my own
  149.     event loop, but since there is no easy way to PostEvent()
  150.     from one apps context to another this is not done. If you
  151.     have a suggestion to help me, I would like to make this
  152.     change.
  153.  
  154.  
  155. Finally, I want this to be a stable mechanism for something that you
  156. shouldn't be able to do. Despite the interface guidelines, there may
  157. be a use for doing this. Please send me bug reports and suggestions
  158. for improving this tool.
  159.  
  160. Matt Slot
  161. fprefect@umich.edu
  162.